QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top |

Component-Defined Functions

This section defines the effect-specific functions that you may supply in your effect components. This section is only of interest to developers who are creating their own effects components; if you are writing an application that uses QuickTime video effects, you can skip this section.

The functions defined in this section are those called by the Component Manager through your component's dispatch function (see "What Effects Components Do" ).

Note
The interfaces to these functions are described assuming you are using Apple's component dispatch helper code and the sample effect framework as described in "The Sample Effect Component" . Apple strongly recommends that you re-use these code samples where possible when implementing your own effect components.

If you are using the sample effect component, you can use the default implementations of several of these functions in most circumstances.

MyEffectSetup

The Component Manager calls this function when a sequence of frames is about to be rendered.



 
ComponentResult MyEffectSetup (

                     EffectGlobals *glob,

                     CodecDecompressParams *decompressParams);

glob: A pointer to the effect's global data structure.
decompressParams: Information about the sequence that is about to be decompressed.

DISCUSSION

This function is called immediately before a client application such as MoviePlayer calls your component to render a sequence of frames.

Your component should examine the capabilities field of the decompressParams data structure to ensure that it can meet the requirements for executing this sequence. In particular, it should check the bit depth and pixel format requirements of the sequence. If the sequence requires a bit depth and pixel format combination that your component does not support, this function should return the nearest supported combination in the decompressParams->capabilities field. In this case, QuickTime will redirect all source and destination bitmaps through offscreen graphics worlds that have the bit depth and pixel format characteristics that you specify.

MyEffectBegin

The Component Manager calls this function to request that your component prepare to render a single frame of its effect.



 
ComponentResult MyEffectBegin (

                     EffectGlobals *glob,

                     CodecDecompressParams *decompressParams,

                     EffectsFrameParamsPtr effect);

glob: A pointer to the effect's global data structure.
decompressParams: Information about the current sequence of frames.
effect: The parameters describing this frame.

DISCUSSION

This function is called immediately before your MyEffectRenderFrame function. Your MyEffectBegin function should ensure that the information it holds about the current source and destination buffers and the parameter values for the effect are valid. If any of these have changed since the last call to MyEffectBegin , the new values should be read from the appropriate data structures.

This function is guaranteed to be called synchronously. In particular, this means you can allocate and move memory, and can call functions that allocate or move memory.

MyEffectRenderFrame

The Component Manager calls this function to request that your component render a single frame of its effect.



 
ComponentResult MyEffectRenderFrame (

                     EffectGlobals *glob,

                     EffectsFrameParamsPtr effect);

glob: A pointer to the effect's global data structure.
effect: The parameters describing this frame.

DISCUSSION

This function is called by a client application when your effect component needs to render a single frame of your effect. This function contains the implementation of your effect.

Warning
This function is not guaranteed to be called synchronously. This means your function implementation must not allocate or move memory, or call any function that allocates or moves memory, in response to this call.

MyEffectCancel

The Component Manager calls this function to stop processing of the current effect.



 
ComponentResult MyEffectCancel (

                     EffectGlobals *glob,

                     EffectsFrameParamsPtr effect);

glob: A pointer to the effect's global data structure.
effect: The parameters describing this frame.

DISCUSSION

This function is called by a client application (which may be QuickTime) to halt the rendering of the current sequence of frames before the last frame has been rendered. If your component is running synchronously, it should simply return noErr ; no further calls to your MyEffectRenderFrame function will be made for this sequence.

If your component is running asynchronously, this function should dequeue all outstanding render frame requests, then return noErr .

MyEffectGetCodecInfo

The Component Manager calls this function to request information about the component.



 
ComponentResult MyEffectGetCodecInfo (

                     EffectGlobals *glob,

                     CodecInfo *info);

glob: A pointer to the effect's global data structure.
info: A pointer to the data structure that will contain the codec information.

DISCUSSION

This function is called by a client application (which may be QuickTime) to request information about your effect component. Your function should fill out the CodecInfo data structure passed to it. You can use the GetComponentResource function to retrieve a 'cdci' resource that stores this information if you have provided one in your component.

RESULT CODES

`noErr`	0	The function successfully filled out the `info` field.
`paramErr`	-50	Your function should return this value if the `info` parameter contains `nil` .

MyEffectGetParameterListHandle

The Component Manager calls this function to request a parameter description for this component.



 
ComponentResult MyEffectGetParameterListHandle (

                     EffectGlobals *glob,

                     Handle theHandle);

glob: A pointer to the effect's global data structure.
theHandle: A pointer to a handle that will contain the parameter description of this effect.

DISCUSSION

This function is called by a client application (which may be QuickTime) to request a parameter description for your effect. This function can use the GetComponentResource function to retrieve an'atms' resource that stores this information if you have provided one in your component.

MyEffectGetSpeed

The Component Manager calls this function to request information about the rendering speed of this effect component.



 
long MyEffectGetSpeed (

                     EffectGlobals *glob,

                     QTAtomContainer parameters,

                     Fixed *pFPS)

glob: A pointer to the effect's global data structure.
parameters: The current parameter values for this effect.
pFPS: A pointer to a Fixed value that will contain the rendering speed of this effect on exit.

DISCUSSION

This function is called by a client application (which may be QuickTime) to request information about the rendering speed of your effect. This function should return a Fixed value in pFPS , which represents the rendering speed in frames-per-second of the effect.

If your effect can render in real time, it should return a value of effectIsRealtime . Otherwise, you should return an estimate of the number of frames your effect can render per second. Because rendering speeds are hardware-dependent, effect authors can choose to measure actual rendering speeds in this function. Alternatively, effect authors can choose to return a single value for all hardware configurations, estimating the value for a reference hardware platform.

Apple recommends that the values returned are rounded down to the nearest common frames-per-second value, such as 15, 24 or 30.

MyEffectValidateParameters

If your effect implements this optional function, the Component Manager calls it whenever the user changes a parameter value in the standard parameter dialog box, or attempts to dismiss the dialog.



 
ComponentResult MyEffectValidateParameters (

                     EffectGlobals *glob QTAtomContainer parameters,

                     QTParameterValidationOptions validationFlags,

                     StringPtr errorString);

glob: A pointer to the effect's global data structure.
parameters: The current parameter values for this effect.
validationFlags: Flags that indicate whether a parameter value has changed or the user is dismissing the standard parameter dialog box.
errorString: A StringPtr that is contains an error string explaining to the user why the validation has failed.

DISCUSSION

This optional function is called by a client application (which may be QuickTime) when your effect's standard parameter dialog box is being displayed. It can be called in two circumstances: if the user changes a parameter value in the dialog box; or if the user dismisses the dialog box by clicking OK.

The purpose of this function is to allow your effect to validate its parameters. The current parameter values are passed to the effect in parameters . If all of these values are valid, this function should return noErr . Otherwise, you should return a paramErr and put an explanatory message in the errorString parameter.

| Previous | Chapter Contents | Chapter Top |